Skip to main content

Chat Functions

Use the Chat adapter to manage chat rooms.

Importing the adapter​

To use the functions of the Chat adapter, import it as shown:
import { chatAdapter } from 'epicenter-libs';

The chatAdapter namespace exports functions that make calls to the Chat API.

learn more

For descriptions of the objects used by the Chat adapter functions, read Chat entities.

Create​

Create chat​

Creates a new chat with the provided name, scope, and permit.

note

The chat name provided in the room argument must be unique for the scope.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

The create() function:

  • Constructs a POST request to the endpoint /chat.
  • Accepts optional routing options to customize the API call.
  • Returns the newly created Chat object.
Function signature
export async function create(
    room: string,
    scope: GenericScope,
    permit: Permit,
    optionals: RoutingOptions = {}
): Promise<Chat>

Parameters​

Return value​

A promise that resolves to the newly created Chat object.

Usage example​

import { chatAdapter, SCOPE_BOUNDARY, ROLE } from 'epicenter-libs';

await chatAdapter.create(
  'my-chat-room',
  { scopeBoundary: SCOPE_BOUNDARY.GROUP, scopeKey: '00000165ad4e6a3cd22b993340b569486321' },
  { readLock: ROLE.PARTICIPANT, writeLock: ROLE.PARTICIPANT }
);

Retrieve​

Get chat​

Retrieves a chat by its unique key.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

The get() function:

  • Constructs a GET request to the endpoint /chat/{chatKey}.
  • Accepts optional routing options to customize the network call.
  • Returns the corresponding Chat object.
Function signature
export async function get(
    chatKey: string,
    optionals: RoutingOptions = {}
): Promise<Chat>

Parameters​

  • chatKey (string): The unique key identifying the chat.
  • optionals (RoutingOptions, optional): Network call option overrides.

Return value​

A promise that resolves to the corresponding Chat object.

Usage example​

import { chatAdapter } from 'epicenter-libs';

await chatAdapter.get('00000165ad4e6a3cd22b993340b658423159');

Query for chats​

Searches for chats based on the provided search criteria, returning a paginated list.

learn more

For reference on search filters, read Filter and sort syntax.

Permissions​

Requires a role of ANONYMOUS or higher.

Function description​

The query() function:

  • Constructs a GET request to the endpoint /chat/search with the search criteria provided in searchOptions.
  • Accepts optional routing options to customize the API call.
  • Returns a paginated list of Chat objects.
Function signature
export async function query(
    searchOptions: GenericSearchOptions,
    optionals: RoutingOptions = {}
): Promise<Page<Chat>>

Parameters​

  • searchOptions (GenericSearchOptions): Options for filtering and sorting the search.
    • filter (string[], optional): Array of filter conditions. Multiple conditions can be combined.
    • sort (string[], optional): Array of sorting criteria.
    • first (number, optional): The index of the first item to return (default is 0).
    • max (number, optional): The maximum number of items per page.
  • optionals (RoutingOptions, optional): Network call options overrides.

Return value​

A promise that resolves to a Page<Chat> containing the list of chats found.

Usage example​

import { chatAdapter } from 'epicenter-libs';

await chatAdapter.query({
  filter: [
    'room|=my-chat-room|my-other-chat|room-three',
    'scopeBoundary=GROUP',
    'created>=2022-01-03T20:30:53.054Z',
  ],
  sort: ['+chat.created'],
  first: 3,
  max: 10,
});

Update​

The only property of a chat that can be updated is its permit, which controls who has read and/or write permissions to the chat.

Manage chat access​

To update the permit for a chat, call the updatePermit() function.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

The updatePermit() function:

  • Accepts optional routing options to customize the API call.
  • Constructs a PATCH request to the endpoint /chat/{chatKey}.
  • Sends a new Permit object in the request body.
  • Returns the updated Chat object.
Function signature
export async function updatePermit(
    chatKey: string,
    permit: Permit,
    optionals: RoutingOptions = {}
): Promise<Chat>

Parameters​

  • chatKey (string): The unique key identifying the chat.
  • permit (Permit): The new permit.
  • optionals (RoutingOptions, optional): Network call options overrides.

Return value​

A promise that resolves to the updated Chat object.

Usage example​

import { chatAdapter } from 'epicenter-libs';

await chatAdapter.updatePermit(
  '0000018d61f1217b22ce0ae605ff00659e3u',
  { readLock: ROLE.PARTICIPANT, writeLock: ROLE.PARTICIPANT }
);

Chat messages​

Send message​

Sends a message to a chat.

The sendMessage() function offers two options:

  • Send a message to all users in the chat room.
  • Send a private message to one of the users in the chat room.
tip

To send the message only to a specific user, pass the optional userKey parameter.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

The sendMessage() function:

  • Constructs a PUT request to the endpoint /chat/message/{chatKey}.
  • Optionally accepts a userKey to send the message only to a specific user within the chat. If omitted, the message is visible to everyone in the chat room.
  • Sends the provided message in the request body.
  • Returns the created ChatMessage object.
Function signature
export async function sendMessage(
    chatKey: string,
    message: string,
    optionals: { userKey?: string } & RoutingOptions = {}
): Promise<ChatMessage>

Parameters​

  • chatKey (string): The unique key identifying the chat to send the message to.
  • message (string): The text of the message to send.
  • optionals (RoutingOptions, optional): Optional arguments, including network call option overrides.
    • userKey (string, optional): The key of the user to send the message to. If omitted, the message is visible to everyone in the chat room.

Return value​

A promise that resolves to the created ChatMessage object.

Usage example​

import { chatAdapter } from 'epicenter-libs';

// Send a public message to a chat
await chatAdapter.sendMessage('0000017dd3bf540e5ada5b1e058f08f20461', 'hello');

// Send a private message to a specific user within the chat
await chatAdapter.sendMessage(
  '0000017dd3bf540e5ada5b1e058f08f20461',
  'hello, privately',
  { userKey: '000001796733eef0842f4d6d960997018a33' }
);

Get messages​

Retrieves messages from a chat.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

The getMessages() function:

  • Accepts optional routing options to customize the API call.
  • Constructs a GET request to the endpoint /chat/message/{chatKey}.
  • Supports optional pagination parameters such as maxRecords and horizon. For details, read the parameter descriptions below.
  • Returns a list of ChatMessage objects.
Function signature
export async function getMessages(
    chatKey: string,
    optionals: {
        maxRecords?: number,
        horizon?: number,
    } & RoutingOptions = {}
): Promise<ChatMessage[]>

Parameters​

  • chatKey (string): The unique key identifying the chat.
  • optionals ({ maxRecords?: number; horizon?: number; } & RoutingOptions, optional): Optional arguments, including network call option overrides.
    • maxRecords (number, optional): Maximum number of messages to retrieve.
    • horizon (number, optional): The message ID to start from. Messages are retrieved in reverse order from this ID.

Return value​

A promise that resolves to a list of ChatMessage objects.

Usage example​

import { chatAdapter } from 'epicenter-libs';

// Get the chat message with id: 5
await chatAdapter.getMessages(
  '0000017dd3bf540e5ada5b1e058f08f20461',
  { horizon: 5, maxRecords: 1 }
);

// Get the 10 chat messages starting from id 5 (inclusive)
await chatAdapter.getMessages(
  '0000017dd3bf540e5ada5b1e058f08f20461',
  { horizon: 5, maxRecords: 10 }
);